@tanem/svg-injector

What is @tanem/svg-injector?

@tanem/svg-injector is an npm package that allows you to dynamically inject SVG files into the DOM. This can be useful for manipulating SVGs with CSS and JavaScript, improving accessibility, and optimizing performance.

What are @tanem/svg-injector's main functionalities?

Basic SVG Injection

This feature allows you to inject an SVG file into a specified DOM element. The SVG content will replace the content of the target element.

const SVGInjector = require('@tanem/svg-injector');

const mySVGElement = document.querySelector('#my-svg');
SVGInjector(mySVGElement);

Batch SVG Injection

This feature allows you to inject multiple SVG files into multiple DOM elements in a single call. This is useful for batch processing multiple SVGs at once.

const SVGInjector = require('@tanem/svg-injector');

const svgElements = document.querySelectorAll('.svg-inject');
SVGInjector(svgElements);

Callback Function

This feature allows you to specify a callback function that will be called after all SVGs have been injected. This can be useful for performing additional actions once the injection is complete.

const SVGInjector = require('@tanem/svg-injector');

const mySVGElement = document.querySelector('#my-svg');
SVGInjector(mySVGElement, {
  afterAll: (elementsLoaded) => {
    console.log(`${elementsLoaded.length} SVGs injected`);
  }
});

Other packages similar to @tanem/svg-injector

svg-injector

svg-injector is another popular package for injecting SVGs into the DOM. It offers similar functionality to @tanem/svg-injector but may have different API methods and options.

react-svg

react-svg is a React component for injecting SVGs into the DOM. It is specifically designed for use with React applications and offers a more React-friendly API compared to @tanem/svg-injector.

svg-inline-loader

svg-inline-loader is a Webpack loader that inlines SVGs into your JavaScript bundles. It offers a different approach to SVG injection by integrating directly into the build process.

README

svg-injector

A fast, caching, dynamic inline SVG DOM injection library.

Background

There are a number of ways to use SVG on a page (object, embed, iframe, img, CSS background-image) but to unlock the full potential of SVG, including full element-level CSS styling and evaluation of embedded JavaScript, the full SVG markup must be included directly in the DOM.

Wrangling and maintaining a bunch of inline SVG on your pages isn't anyone's idea of good time, so SVGInjector lets you work with simple tag elements and does the heavy lifting of swapping in the SVG markup inline for you.

Basic Usage

<div id="inject-me" data-src="icon.svg"></div>

import { SVGInjector } from '@tanem/svg-injector'

SVGInjector(document.getElementById('inject-me'))

Avoiding XSS

Be careful when injecting arbitrary third-party SVGs into the DOM, as this opens the door to XSS attacks. If you must inject third-party SVGs, it is highly recommended to sanitize the SVG before injecting. The following example uses DOMPurify to strip out attributes and tags that can execute arbitrary JavaScript. Note that this can alter the behavior of the SVG.

import { SVGInjector } from '@tanem/svg-injector'
import DOMPurify from 'dompurify'

SVGInjector(document.getElementById('inject-me'), {
  beforeEach(svg) {
    DOMPurify.sanitize(svg, {
      IN_PLACE: true,
      USE_PROFILES: { svg: true, svgFilters: true },
    })
  },
})

Live Examples

• Basic Usage: Source | Sandbox
• API Usage: Source | Sandbox
• MooTools: Source | Sandbox
• UMD Build (Development): Source | Sandbox
• UMD Build (Production): Source | Sandbox

API

Arguments

• elements - A single DOM element or array of elements, with src or data-src attributes defined, to inject.
• options - Optional An object containing the optional arguments defined below. Defaults to {}.
  • afterAll(elementsLoaded) - Optional A callback which is called when all elements have been processed. elementsLoaded is the total number of elements loaded. Defaults to () => undefined.
  • afterEach(err, svg) - Optional A callback which is called when each element is processed. svg is the newly injected SVG DOM element. Defaults to () => undefined.
  • beforeEach(svg) - Optional A callback which is called just before each SVG element is added to the DOM. svg is the SVG DOM element which is about to be injected. Defaults to () => undefined.
  • cacheRequests - Optional Use request cache. Defaults to true.
  • evalScripts - Optional Run any script blocks found in the SVG. One of 'always', 'once', or 'never'. Defaults to 'never'.
  • httpRequestWithCredentials - Optional Boolean that indicates whether or not cross-site Access-Control requests should be made using credentials. Defaults to false.
  • renumerateIRIElements - Optional Boolean indicating if SVG IRI addressable elements should be renumerated. Defaults to true.

Example

<div class="inject-me" data-src="icon-one.svg"></div>
<div class="inject-me" data-src="icon-two.svg"></div>

import { SVGInjector } from '@tanem/svg-injector'

SVGInjector(document.getElementsByClassName('inject-me'), {
  afterAll(elementsLoaded) {
    console.log(`injected ${elementsLoaded} elements`)
  },
  afterEach(err, svg) {
    if (err) {
      throw err
    }
    console.log(`injected ${svg.outerHTML}`)
  },
  beforeEach(svg) {
    svg.setAttribute('stroke', 'red')
  },
  cacheRequests: false,
  evalScripts: 'once',
  httpRequestWithCredentials: false,
  renumerateIRIElements: false,
})

Installation

⚠️This library uses Array.from(), so if you're targeting browsers that don't support that method, you'll need to ensure an appropriate polyfill is included manually. See this issue comment for further detail.

$ npm install @tanem/svg-injector

There are also UMD builds available via unpkg:

• https://unpkg.com/@tanem/svg-injector/dist/svg-injector.umd.development.js
• https://unpkg.com/@tanem/svg-injector/dist/svg-injector.umd.production.js

Credit

This is a fork of a library originally developed by Waybury for use in iconic.js, part of the Iconic icon system.

License

MIT

Changelog

v10.1.68 (2023-11-12)

Full Changelog

:house: Internal

• #1464 Update dependency @types/chai to v4.3.8 (@renovate[bot])
• #1463 Update babel monorepo to v7.23.2 (@renovate[bot])
• #1462 Update dependency parcel to v2.10.0 (@renovate[bot])
• #1461 Update dependency @types/chai to v4.3.7 (@renovate[bot])
• #1460 Update typescript-eslint monorepo to v6.7.5 (@renovate[bot])